SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_qt.idb/usr/freeware/catman/p_man/cat3/qcache.Z/qcache

Text File | 1998-10-28 | 15.0 KB | 265 lines

     QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))       QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))



     NNNNAAAAMMMMEEEE
      QCache - Template class that provides    a cache    based on char*
      keys

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
      #include <qcache.h>

      Inherits QGCache.

    PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrrssss
      QQQQCCCCaaaacccchhhheeee (((( ccccoooonnnnsssstttt QQQQCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&&    cccc ))))
      QQQQCCCCaaaacccchhhheeee (((( iiiinnnntttt _m_a_x_C_o_s_t====111100000000,,,, iiiinnnntttt    _s_i_z_e====11117777,,,, bbbboooooooollll _c_s
      ~~~~QQQQCCCCaaaacccchhhheeee ()
      QQQQCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>>&&&&    ooooppppeeeerrrraaaattttoooorrrr==== (((( ccccoooonnnnsssstttt QQQQCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc ))))
      iiiinnnntttt mmmmaaaaxxxxCCCCoooosssstttt (((()))) ccccoooonnnnsssstttt
      iiiinnnntttt ttttoooottttaaaallllCCCCoooosssstttt    (((()))) ccccoooonnnnsssstttt
      vvvvooooiiiidddd sssseeeettttMMMMaaaaxxxxCCCCoooosssstttt (((( iiiinnnntttt    mmmm ))))
      vvvviiiirrrrttttuuuuaaaallll uuuuiiiinnnntttt ccccoooouuuunnnntttt (((())))    ccccoooonnnnsssstttt
      uuuuiiiinnnntttt ssssiiiizzzzeeee (((()))) ccccoooonnnnsssstttt
      bbbboooooooollll iiiissssEEEEmmmmppppttttyyyy (((()))) ccccoooonnnnsssstttt
      bbbboooooooollll iiiinnnnsssseeeerrrrtttt ((((    ccccoooonnnnsssstttt cccchhhhaaaarrrr **** _k,,,,    ccccoooonnnnsssstttt ttttyyyyppppeeee **** _d,,,,    iiiinnnntttt _c
      bbbboooooooollll rrrreeeemmmmoooovvvveeee ((((    ccccoooonnnnsssstttt cccchhhhaaaarrrr **** kkkk ))))
      ttttyyyyppppeeee****    ttttaaaakkkkeeee (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr **** kkkk ))))
      vvvviiiirrrrttttuuuuaaaallll vvvvooooiiiidddd cccclllleeeeaaaarrrr (((())))
      ttttyyyyppppeeee****    ffffiiiinnnndddd (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr **** _k,,,, bbbboooooooollll _r_e_f====TTTTRRRRUUUUEEEE )))) ccccoooonnnnsssstttt
      ttttyyyyppppeeee****    ooooppppeeeerrrraaaattttoooorrrr[[[[]]]] (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr    **** kkkk )))) ccccoooonnnnsssstttt
      vvvvooooiiiidddd ssssttttaaaattttiiiissssttttiiiiccccssss (((()))) ccccoooonnnnsssstttt

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      The QCache class is a    template class that provides a cache
      based    on char* keys.

      QCache is implemented    as both    a template and a macro class.
      Define a template instance QCache<X> to create a cache that
      operates on pointers to X, or    X*.

      A cache is a least recently used (LRU) list of cache items.
      Each cache item has a    cost. The sum of item costs,
      totalCost(), will not    exceed the maximum cache cost,
      maxCost(). If    inserting a new    item would cause the total
      cost to exceed the maximum cost, the least recently used
      items    in the cache are deleted.

      Apart    from insert, by    far the    most important function    is
      find() (which    also exists as operatior[]). This function
      looks    up an item, returns it,    and by default marks it    as
      being    the least recently used    item.

      There    are also methods to remove() an    object from the    cache
      and delete it, and to    take() an object out of    the cache
      without deleting it.




     Page 1                         (printed 9/22/98)






     QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))       QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))



      The keys for the cache can be    case-sensitive or not, or
      deeply copied    or not.    The constructor    lets you decide.

      QCache, as it    must, takes over ownership of the items    you
      insert. That implies that it will delete the items at    its
      discretion, and that you must    _n_o_t delete them. There is one
      exception, however: If the cost of an    object you try to
      insert() is higher than the allowed total cost of the    cache,
      insert() returns FALSE and in    this case you must delete the
      object yourself.

      In addition to totalCost() and maxCost()/setMaxCost(), there
      are access functions to obtain the number of items in    the
      cache    (count()), the size of the hash    array (size(), set
      using    the constructor) and whether the cache is empty    (you
      guessed it: isEmpty()). Finally, there is a statistics(),
      which    prints various cache statistics    on stdout.

      There    is also    a QCacheIterator which may be used to traverse
      the items in the cache in arbritrary order.

      See also: QCacheIterator, QIntCache and Collection Classes

     MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
     QQQQCCCCaaaacccchhhheeee::::::::QQQQCCCCaaaacccchhhheeee (((( ccccoooonnnnsssstttt QQQQCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc ))))
      For internal use only.

     QQQQCCCCaaaacccchhhheeee::::::::QQQQCCCCaaaacccchhhheeee (((( iiiinnnntttt mmmmaaaaxxxxCCCCoooosssstttt====111100000000,,,, iiiinnnntttt ssssiiiizzzzeeee====11117777,,,, bbbboooooooollll ccccssss====TTTTRRRRUUUUEEEE,,,, bbbboooooooollll
      cccckkkk====TTTTRRRRUUUUEEEE ))))
      Constructs an    empty cache with maximum allowed total cost
      _m_a_x_C_o_s_t, optimized to    contain    a bit less than    _s_i_z_e items,
      with case-sensitive keys if _c_s is TRUE (the default) and
      case-insensitive keys    if _c_s is FALSE,    and whose keys are
      deeply copied    on insertion (the default) and shallowly
      copied of _c_k is FALSE.

     QQQQCCCCaaaacccchhhheeee::::::::~~~~QQQQCCCCaaaacccchhhheeee (((())))
      Destroys the object and all objects in it.

     vvvvooooiiiidddd QQQQCCCCaaaacccchhhheeee::::::::cccclllleeeeaaaarrrr    (((()))) [[[[vvvviiiirrrrttttuuuuaaaallll]]]]
      Removes all items from the cache, and    deletes    them.

      All cache iterators that operate this    on cache are reset.

      See also: remove() and take().

      Reimplemented    from QCollection.

     uuuuiiiinnnntttt QQQQCCCCaaaacccchhhheeee::::::::ccccoooouuuunnnntttt    (((()))) ccccoooonnnnsssstttt [[[[vvvviiiirrrrttttuuuuaaaallll]]]]
      Returns the number of    items in the cache.

      See also: totalCost().



     Page 2                         (printed 9/22/98)






     QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))       QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))



      Reimplemented    from QCollection.

     ttttyyyyppppeeee **** QQQQCCCCaaaacccchhhheeee::::::::ffffiiiinnnndddd (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr ****    kkkk,,,, bbbboooooooollll    rrrreeeeffff====TTTTRRRRUUUUEEEE )))) ccccoooonnnnsssstttt
      Returns the item associated with \ k,    or null    if the key
      does not exist in the    cache. If _r_e_f is TRUE (the default),
      the item is moved to the front of the    LRU list.

      If there are two or more items with equal keys, then the one
      that was inserted last is returned.

     bbbboooooooollll QQQQCCCCaaaacccchhhheeee::::::::iiiinnnnsssseeeerrrrtttt (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr ****    kkkk,,,, ccccoooonnnnsssstttt ttttyyyyppppeeee ****    dddd,,,, iiiinnnntttt cccc====1111,,,,
      iiiinnnntttt pppp====0000 ))))
      Inserts the item _d into the cache with key _k,    cost and
      priority _p, and returns TRUE if it is    successful and FALSE
      if it    fails.

      The cache's size is limited, and if the total    cost is    too
      high,    QCache will delete some    of the least-used objects.

      WWWWaaaarrrrnnnniiiinnnngggg:::: If this function returns FALSE, you must delete _d
      yourself. Additionally, be very careful about    using _d    after
      calling this function, as any    other insertions into the
      cache, from anywhere in the application, or within Qt
      itself, could    cause the object to be discarded from the
      cache, and the pointer to become invalid.

     bbbboooooooollll QQQQCCCCaaaacccchhhheeee::::::::iiiissssEEEEmmmmppppttttyyyy (((()))) ccccoooonnnnsssstttt
      Returns TRUE if the cache is empty, or TRUE if there is at
      least    one object in it.

     iiiinnnntttt QQQQCCCCaaaacccchhhheeee::::::::mmmmaaaaxxxxCCCCoooosssstttt (((()))) ccccoooonnnnsssstttt
      Returns the maximum allowed total cost of the    cache.

      See also: setMaxCost() and totalCost().

     QQQQCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>>&&&& QQQQCCCCaaaacccchhhheeee::::::::ooooppppeeeerrrraaaattttoooorrrr==== (((( ccccoooonnnnsssstttt QQQQCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc ))))
      For internal use only.

     ttttyyyyppppeeee **** QQQQCCCCaaaacccchhhheeee::::::::ooooppppeeeerrrraaaattttoooorrrr[[[[]]]] (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr **** kkkk    )))) ccccoooonnnnsssstttt
      Returns the item associated with _k, or null if _k does    not
      exist    in the cache, and moves    the item to the    front of the
      LRU list.

      If there are two or more items with equal keys, then the one
      that was inserted last is returned.

      This is the same as find( k, TRUE ).

      See also: find().

     bbbboooooooollll QQQQCCCCaaaacccchhhheeee::::::::rrrreeeemmmmoooovvvveeee (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr ****    kkkk ))))
      Deletes the item associated with _k, and returns TRUE if the



     Page 3                         (printed 9/22/98)






     QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))       QQQQCCCCaaaacccchhhheeee((((3333qqqqtttt))))



      item was present in the cache    or FALSE if it was not.

      If there are two or more items with equal keys, then the one
      that was inserted last is is deleted.

      All iterators    that refer to the removed item are set to
      point    to the next item in the    cache's    traversal order.

      See also: take() and clear().

     vvvvooooiiiidddd QQQQCCCCaaaacccchhhheeee::::::::sssseeeettttMMMMaaaaxxxxCCCCoooosssstttt (((( iiiinnnntttt mmmm ))))
      Sets the maximum allowed total cost of the cache to _m. If
      the current total cost is above _m, some items    are deleted
      immediately.

      See also: maxCost() and totalCost().

     uuuuiiiinnnntttt QQQQCCCCaaaacccchhhheeee::::::::ssssiiiizzzzeeee (((()))) ccccoooonnnnsssstttt
      Returns the size of the hash array used to implement the
      cache. This should be    a bit bigger than count() is likely to
      be.

     ttttyyyyppppeeee **** QQQQCCCCaaaacccchhhheeee::::::::ttttaaaakkkkeeee (((( ccccoooonnnnsssstttt cccchhhhaaaarrrr ****    kkkk ))))
      Takes    the item associated with _k out of the cache without
      deleting it, and returns a pointer to    the item taken out, or
      null if the key does not exist in the    cache.

      If there are two or more items with equal keys, then the one
      that was inserted last is taken.

      All iterators    that refer to the taken    item are set to    point
      to the next item in the cache's traversal order.

      See also: remove() and clear().

     iiiinnnntttt QQQQCCCCaaaacccchhhheeee::::::::ttttoooottttaaaallllCCCCoooosssstttt (((()))) ccccoooonnnnsssstttt
      Returns the total cost of the    items in the cache. This is an
      integer in the range 0 to maxCost().

      See also:  setMaxCost().

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      hhhhttttttttpppp::::////////wwwwwwwwwwww....ttttrrrroooollllllll....nnnnoooo////qqqqtttt////qqqqccccaaaacccchhhheeee....hhhhttttmmmmllll

     CCCCOOOOPPPPYYYYRRRRIIIIGGGGHHHHTTTT
      Copyright 1992-1997 Troll Tech AS.  See the LICENSE file
      included in the distribution for a complete license
      statement.

     AAAAUUUUTTTTHHHHOOOORRRR
      Generated automatically from the source code.




     Page 4                         (printed 9/22/98)